home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The World of Computer Software
/
The World of Computer Software.iso
/
wstyl113.zip
/
WSTYLE.DOC
< prev
next >
Wrap
Text File
|
1992-02-20
|
84KB
|
2,179 lines
The Wintertree Writing Style Analyzer
Wintertree Software Inc.
Wintertree Software Inc. makes no warranty, expressed or implied,
for the fitness of this product for any purpose. Wintertree
Software Inc. will not be held responsible for any loss or
damage, direct or indirect, caused by the use or misuse of this
product.
WStyle is a "shareware program" and is provided at no charge to
the user for evaluation. Feel free to share it with your
friends, but please do not give it away altered or as part of
another system. The essence of "user-supported" software is to
provide personal computer users with quality software without
high prices, and yet to provide incentive for programmers to
continue to develop new products. If you find WStyle useful and
want to continue using it, you must make a registration payment
of $25.00 to Wintertree Software Inc. The $25.00 registration
fee will license one copy for use on any one computer at any one
time.
Commercial users of WStyle must register and pay for their copies
within 30 days of first use or their license is withdrawn.
Site-license arrangements may be made by contacting Wintertree
Software Inc.
You are encouraged to pass a copy of WStyle along to your friends
for evaluation. Please encourage them to register their copy if
they find that they can use it. All registered users will
receive a copy of the latest version of WStyle and a printed copy
of the user's guide. Please see ORDER.TXT for ordering
instructions.
MS-DOS is a trademark of Microsoft Corporation.
WordPerfect is a trademark of WordPerfect Corporation.
The Wintertree Writing Style Analyzer and User's Guide are
Copyright 1992 by Wintertree Software Inc.
Wintertree Software Inc.
43 Rueter Street, Nepean, Ontario, Canada K2J 3Z9
(613) 825-6271
Table of Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1
Installing WStyle . . . . . . . . . . . . . . . . . . . . 1
About Writing Style . . . . . . . . . . . . . . . . . . . . . 2
Using WStyle . . . . . . . . . . . . . . . . . . . . . . . . 3
Writing-Style Statistics . . . . . . . . . . . . . . . . . . 9
Writing-Style Problems . . . . . . . . . . . . . . . . . . 13
Customizing WStyle . . . . . . . . . . . . . . . . . . . . 17
Setting Options . . . . . . . . . . . . . . . . . . . . 17
Configuring WStyle . . . . . . . . . . . . . . . . . . . 19
Editing Problem Patterns . . . . . . . . . . . . . . . . 25
Limitations . . . . . . . . . . . . . . . . . . . . . . . . 29
References . . . . . . . . . . . . . . . . . . . . . . . . 31
Wintertree Software Inc. WStyle User's Guide
Introduction
The Wintertree Writing-Style Analyzer -- WStyle
for short (pronounced "Double-you Style") -- helps
improve your writing style in two ways. First, it
examines your writing for common problems, such as
redundant words, wordy phrases, and awkward
sentence structure. Second, it analyzes your
writing style and presents statistics that tell
you where your writing is weak and where it is
strong. Although WStyle is not a substitute for an
independent review, it can help you to write more
clearly and directly and avoid common writing-
style errors.
System WStyle runs on MS-DOS-compatible computers. You
Requirements can install WStyle on a hard disk or a floppy
diskette. WStyle can check files produced by most
word-processing programs.
README.TXT The WStyle distribution contains a file called
README.TXT. This file describes any changes made
to WStyle since this manual was printed. We
suggest you read README.TXT before using WStyle.
Installing WStyle
To install WStyle, create a directory called
WSTYLE. Next, copy the following files to the
WSTYLE directory:
WSTYLE.EXE
WSTYLE.WSP
WSTYLE.INF
Finally, edit the PATH environment variable in
your AUTOEXEC.BAT file to include the WSTYLE
directory. Refer to your MS-DOS user's guide for
instructions on how to do this. For example, if
you created the WSTYLE directory under C:\, you
might edit your PATH variable to look like this:
PATH=C:\DOS;C:\123;C:\WP51;C:\WSTYLE
1
WStyle User's Guide Wintertree Software Inc.
About Writing Style
The term "writing style" may mean different things
to different people. Certainly, not everyone
agrees on what constitutes good style.
By "writing style" we mean the characteristics of
writing that refer to its quality. There is good
and bad writing style and everything between.
Writing style is a step beyond the competency of
correct spelling, punctuation, and grammar.
Writing style is a measure of the quality of a
written work.
We have taken the position that the goal of
writing is to convey information to the reader.
Good writing, then, conveys information
effectively: it is clear and direct. In developing
WStyle, we researched the factors that affect how
well information is conveyed. Because WStyle is a
computer program, we were forced to concentrate on
those factors that we could feasibly program. We
arrived at these four general factors:
1. Use of the active voice over the passive
voice
2. Word economy
3. Readability
4. Word choice.
Many other important factors, such as organization
and elegance, were omitted because we could find
no feasible way of incorporating them into a
computer program. The "Limitations" section states
what WStyle can and cannot do.
One final note on writing style: We do not
consider ourselves experts on this subject. WStyle
is the product of many hours of research. Most of
the ideas in WStyle are the brainchildren and
learned observations of the people whose books are
cited in the "References" section.
2
Wintertree Software Inc. WStyle User's Guide
Using WStyle
This section describes how to run and operate
WStyle.
WStyle analyzes the text in a document prepared
using a word-processing program. It points out
common writing-style problems as it goes. When it
has completed its analysis, WStyle displays some
statistics which profile your writing style.
You can tell WStyle which document to check in two
ways:
1. By entering the name of the document file on
the command line when you start WStyle
2. By selecting the "Check doc" action from
WStyle's main screen.
Specifying the The easiest way to run WStyle is to enter the name
document name on of the program, "WStyle," on the DOS command line
the command line followed by the document file name. For example,
if you want to analyze a document called MEMO.TXT,
and MEMO.TXT is in the current directory, enter
the following command when you see the DOS prompt:
wstyle memo.txt
If you prefer, you can omit the document file name
from the command line. You then tell WStyle which
document to check by invoking the "Check doc"
action (F1) from WStyle's main screen (described
below).
Problem-reporting You can enter two options on WStyle's command
level options line: the problem-reporting level and the target
reader's level. The "Customizing WStyle" section
defines the meanings of these options. You can
enter the problem-reporting level option ("/r") on
the command line like this:
/r n
"n" is the problem reporting level (0 - 9).
3
WStyle User's Guide Wintertree Software Inc.
Target-reader's The "/t" option defines the target-reader's level:
level option
/t n
"n" is the number of years of schooling you expect
the target reader to have. For example, to analyze
a document called MEMO.TXT, set the problem-
reporting level to 6, and the target-reader's
level to 11.5, enter the following command line:
wstyle /r 6 /t 11.5 memo.txt
Main screen If you run WStyle with a document file name on the
actions command line, it analyzes your document
immediately. If you omit the document file name
from the command line, WStyle displays a series of
actions on the bottom line of the screen:
F1-Check Doc F2-Options F3-Patterns Esc-Exit
Check Doc (F1) Tells WStyle to check a document. WStyle displays
a list of files; see "Selecting a File," below.
Options (F2) Lets you change some of WStyle's options. See the
"Customizing WStyle" section for more details.
Patterns (F3) Lets you view and edit WStyle's writing-style
problem patterns. See the "Customizing WStyle"
section for more details.
Exit (Esc) Exits WStyle and returns to DOS.
Selecting a file When you invoke the "Check Doc" action, WStyle
presents a file-selection form. The file-selection
form lists all the files in a directory which
match a specified pattern. The top line of the
form shows the directory and pattern. Both the
directory and pattern are changeable.
WStyle highlights one of the file names in the
form. You can highlight a different file by using
the arrow keys. If the directory contains more
files than can fit on the display, the "Page Up"
and "Page Down" keys display more names.
Note: The file-selection form can keep track of up
to 128 file names. If the pattern matches more
than this number of files, WStyle replaces the
last file name with "Too Many!" When this happens,
edit the file-name pattern (see below) to make it
4
Wintertree Software Inc. WStyle User's Guide
more specific. For example, change a file-name
pattern like "*.*" to "*.DOC".
File-selection At the bottom of the screen, WStyle displays some
form actions actions:
F1-Open F2-Edit Path Esc-Quit
Open (F1) WStyle opens the highlighted file. If the file
name is a regular file, WStyle checks its
contents. If the file name is a directory, WStyle
enters it and displays its contents.
Edit Path (F2) WStyle lets you edit the current directory name
and file pattern. Use the left- and right-arrow
keys to position the cursor within the path. The
"Delete" key and "Backspace" keys delete
characters. Typed characters are inserted at the
cursor position. Press the "Enter" key when you
are done.
Cancel (Esc) WStyle closes the file-selection form and returns
to the main-screen actions.
Writing-style Regardless of the method you choose to start it,
problem report WStyle examines the text in your document,
collecting information about your writing style
and looking for common writing-style problems.
WStyle display each word it reads from your
document. It also displays a progress bar which
shows you what portion of the document it has
examined. When it encounters a writing-style
problem, WStyle displays a problem report:
The following problem was encountered in
D:\DOC\MEMO.TXT:
Problem: connected together
Description: Redundant
Suggestion: Use "connect"
Note: The writing-style problems which WStyle
reports are really warnings brought to your
attention. The problems do not necessarily
indicate errors in your writing. Unlike a spelling
checker, which states conclusively which words are
spelled incorrectly, WStyle simply points out
places in your writing that match patterns
associated with common writing-style problems. You
must decide whether the problem is significant to
you.
5
WStyle User's Guide Wintertree Software Inc.
Furthermore, do not assume that WStyle detects and
reports all the writing-style problems in your
document. See the "Limitations" section for a more
detailed description of what WStyle can and cannot
do.
Problem The problem report describes the writing-style
problem. The "Problem" area shows the word or
phrase containing the problem. The problem word or
phrase is among the last highlighted words in the
context area.
Description The "Description" area contains a description of
the problem. The "Writing Style Problems" section
of this guide explains what the various
descriptions mean.
Suggestion WStyle offers in the "Suggestion" area of the
problem report a suggestion for correcting or
improving your text. Sometimes WStyle suggests a
different wording of a phrase. Sometimes the
problem is a symptom of poor or awkward sentence
structure, so WStyle suggests that the entire
sentence be rewritten. Sometimes the "problem" is
really a warning -- WStyle may warn you that you
have used a word which people often use
incorrectly, even if you have used the word
correctly. The "Suggestion" area contains the
correct definition of the word you used, so you
can verify you used it correctly.
Note: The "Ignore" action (F4) prevents WStyle
from reporting the displayed problem again for the
remainder of the document. You can also
permanently stop WStyle from reporting certain
problems. See the "Customizing WStyle" section for
instructions.
Problem-report When WStyle displays a problem report, it also
actions presents a series of actions at the bottom of the
screen:
F1-Continue F2-Save F3-Print F4-Ignore
Esc-Quit
You invoke an action by pressing the function key
next to the name of the action.
Continue (F1) WStyle continues analyzing your document. Use it
after you have read the problem report.
6
Wintertree Software Inc. WStyle User's Guide
Save (F2) WStyle saves the problem report in a disk file.
The disk file is saved in the same directory as
the document file, and has the same name as the
document file with a "Wnn" extension ("nn" is a
number ranging from 01 to 99; WStyle uses a new
number for each document checked in the same
directory).
For example, if you invoke the "Save" action while
checking a document called MEMO.NR, WStyle will
save the problem report in a file called MEMO.W01.
The disk file created by WStyle contains the same
problem-report information presented on the
screen.
Print (F3) WStyle prints the problem report on a printer. The
printout contains the same problem report
information presented on the screen.
Ignore (F4) WStyle ignores the displayed problem if it occurs
again in the same document. WStyle will, however,
report the problem if it appears the next time you
check a document. To ignore a problem permanently,
see the "Configuring WStyle" section.
Quit (Esc) WStyle stops checking the document and returns to
the main screen.
Statistics report When WStyle has finished checking your document
(either because it has reached the end or you
selected the "Quit" action), it displays some
writing-style statistics. See the "Writing-Style
Statistics" section for more information.
Correcting You cannot currently edit your document within
problems WStyle to correct reported problems. We suggest
the following procedure for fixing problems
reported by WStyle.
If your word-processing program lets you load more
than one document at a time, save WStyle's problem
reports to a disk file, then load the "Wnn" file
created by WStyle into your word processor with
your document. For example, suppose you have
created a document in WordPerfect called
CHAP1.DOC. Have WStyle check CHAP1.DOC and save
any significant problem reports (use the F2 key).
Exit WStyle, then start WordPerfect. Import
CHAP1.DOC into WordPerfect. Now, enter
7
WStyle User's Guide Wintertree Software Inc.
WordPerfect's "switch" command (Shift/F3) to
switch to the alternate document. Load CHAP1.W01
(actually, the CHAP1.Wnn file with the highest
number) into WordPerfect. Use WordPerfect's
"switch" command to flip between CHAP1.DOC and the
WStyle problem reports as you correct the
document.
If your word processor cannot load more than one
document at a time, print significant problems
displayed by WStyle (use the F3 key). Use the
printout to locate and correct problems. If you do
not have a printer, you must record significant
problem reports by hand for later correction using
your word processor.
8
Wintertree Software Inc. WStyle User's Guide
Writing-Style Statistics
When it has finished checking your document,
WStyle displays some statistics:
Finished checking D:\DOC\MEMO.TXT.
* 605 problems were detected and 106 were
reported.
* The document contains 5824 words and 375
sentences. On average, each word contains 1.7
syllables and each sentence contains 15.5
words.
* 68% of the sentences use the active voice.
Use of the active voice in this document
makes the writing clear and direct.
* On average, the reader must have 12.8 years
of schooling to understand the document.
Suggestion: use smaller words and shorter
sentences to lower the writing to the target
reader's level (10.0 years).
* The overall style score for this document is
84% (excellent).
Problem counts The problem counts show the number of writing-
style problems detected and reported by WStyle.
These numbers will be different if your problem-
reporting level setting prevented some problems
from being reported.
Word and sentence The word and sentence counts show the size of your
counts document in words and sentences. These can be
useful if your writing must meet size
restrictions.
Average word size The average word-size shows the average number of
syllables per word. This statistic tells you
whether you tend to use small words (about 1.0
syllables per word) or large words (more than
about 2.0 syllables per word).
Average sentence The average sentence-length shows the average
length number of words per sentence. This statistic tells
you whether you tend to use short sentences (about
eight words per sentence or fewer) or long
sentences (about 20 words per sentence or more).
Active voice The active-voice percentage shows what portion of
sentences use the active voice. The active voice
9
WStyle User's Guide Wintertree Software Inc.
is associated with clear, direct writing.
Sentences written in the active voice use action
verbs (verbs that describe action), as opposed to
passive verbs (verbs that describe conditions or
states of being). Text written in the passive
voice has a vague, detached quality when read.
Passive verbs WStyle treats forms of the verb "to be" as passive
verbs. WStyle considers the following as forms of
the verb "to be": "be," "is," "was," "were,"
"been," "are," and "am." These words appearing in
contractions (such as "isn't" and "weren't") are
also considered passive.
Rewriting passive To make your writing more direct, look for
sentences sentences containing passive verbs and try to
rewrite them. Often, the subject of passive
sentences is implied, as in the following example.
"The report will be prepared in the near
future."
Adding a subject makes the sentence clearer.
"The report will be prepared by our staff in
the near future."
The sentence is still indirect and passive; it
uses a passive verb ("be"). Moving the subject
("our staff") to the beginning eliminates the
passive verb and makes the sentence active,
direct, and clear.
"Our staff will prepare the report soon."
When the passive Mixing a few passive-voice sentences (perhaps
voice is 25-30 percent) with active-voice sentences may
appropriate improve the rhythm and break up the
newspaper-style monotony of text written entirely
in active-voice sentences. In technical writing
especially, the passive voice is often appropriate
since the subject may be less significant than the
action or object.
Readability WStyle displays a readability grade. The
readability grade shows the approximate number of
years of schooling on average needed to understand
the document. The readability grade is based on
the number of "big" words versus the number of
10
Wintertree Software Inc. WStyle User's Guide
"small" words and the average sentence length. The
statistic is taken from a readability formula
called the "Fog Index."
WStyle compares the readability grade for your
document with the value you supplied for the
target-reader's level (see the "Customizing
WStyle" section). If they are significantly
different, WStyle offers some advice on changing
your writing to suit the target-reader's level.
Overall-style The overall-style statistic is a general rating of
score your writing style. The score is expressed as a
percentage, with 100% being the best possible
score. A word which qualifies the score follows
the percentage.
The overall-style score is based on the following
factors:
1. Active voice: The portion of sentences that
use only active verbs.
2. Word economy: The ratio of words that convey
meaning (verbs, nouns, adjectives, and
adverbs) to supporting words (prepositions,
articles, etc.).
3. Readability: The difference between the
document's readability grade and the target-
reader's level.
4. Word choice: Ratio of direct, active verbs
and concrete nouns to abstract nouns and
verbs transformed to nouns (e.g., "construct"
vs. "construction"; "establish" vs.
"establishment"; "advocate" vs. "advocacy").
Improving the To improve the overall-style score, concentrate on
overall-style the areas listed below.
score
Use the active voice. Consider rewriting sentences
containing passive verbs.
Rewrite wordy phrases containing several articles
and prepositions:
* "the findings of the committee" becomes "the
committee's findings"
11
WStyle User's Guide Wintertree Software Inc.
* "at the present time" becomes "now"
* "on the advice of our attorney" becomes "our
attorney advised us to"
Follow WStyle's advice on adjusting word and
sentence lengths to suit the target reader.
Avoid abstract nouns and verbs transformed to
nouns. Turn patterns like "the ...tion" of and
"the ...ment of" back into verbs.
Statistical At the bottom of the screen, WStyle displays some
report actions actions:
F2 Save F3 Print Esc Done
Save (F2) WStyle saves the statistical report to a disk
file. WStyle appends the report to the same disk
file used to save problem reports (the "Wnn"
file). See the "Using WStyle" section for more
information.
Print (F3) WStyle prints the statistical report.
Done (Esc) WStyle returns to the main screen.
12
Wintertree Software Inc. WStyle User's Guide
Writing-Style Problems
WStyle checks documents for the common writing-
style problems listed below.
American spelling WStyle reports spelling that is inconsistent with
the spelling preference you selected (see the
"Customizing WStyle" section). If you selected a
preference for British spelling, WStyle reports
any words spelled in the American style (e.g.,
"defense", "color", and "traveling").
Archaic Words that are no longer in common usage.
Awkward Words and phrases that are too informal or do not
read well, although they may not be in error.
British spelling WStyle reports spelling that is inconsistent with
the spelling preference you selected (see the
"Customizing WStyle" section). If you selected a
preference for American spelling, WStyle reports
any words spelled in the British style (e.g.,
"defence", "colour", and "travelling").
Can often be Some words can be omitted without altering the
omitted meaning or impairing the readability of a
sentence. For example, "that" can safely be
omitted in the sentence, "He told me that he was
coming." Some occurrences of "that" cannot be
removed: "I want that one."
Classifying a Phrases that turn a single object into a class,
singular such as "this kind of a car" (should be "this kind
of car").
Confusing word Words that may be misinterpreted, such as
"biweekly". Some people interpret "biweekly" to
mean "twice per week" while others interpret it as
"once every two weeks."
Contraction WStyle checks for common contractions (e.g.,
"can't" and "won't") which should be expanded in
formal writing.
Double comparison Comparison adjectives and adverbs such as "faster"
and "fastest" which are themselves qualified with
comparison adverbs, such as "less" or "most." For
example, "most fastest," "more better," and "less
smaller."
13
WStyle User's Guide Wintertree Software Inc.
Double negative WStyle detects some cases of negative words which
are qualified by negative adjectives, such as "not
uncommon." These are unnecessarily confusing to
the reader.
Doubled word The same word appearing twice in a row, as in
"Paris in the the spring."
Incorrect form of This abbreviation occurs incorrectly so often that
"e.g." WStyle checks for it specifically. The correct
form is "e.g.," as in "e.g., the sun, the moon,
and the stars."
Incorrect form of This abbreviation occurs incorrectly so often that
"i.e." WStyle checks for it specifically. The correct
form is "i.e.," as in "i.e., the reset switch."
Jargon Words with a technical meaning applied in non-
technical writing ("parameter" and "interface") or
words and phrases commonly associated with
"managementspeak" ("time frame" and "prioritize").
Last word of Prepositions (such as "for," "with," or "to")
sentence is a appearing as the last word of a sentence. While
preposition this style is gaining acceptance, a sentence
ending with a preposition may benefit from
rewriting.
Missing or Periods or commas not followed by a space ("Mix
incorrect spacing butter, eggs,and sugar...") or incorrectly
preceded by a space ("The old man tipped his
hat ,then disappeared.") These problems are
usually typographical errors.
Often confused Words that people often confuse with other words.
with... These words may be confused because they sound
similar ("affect" and "effect"). They may also be
confused because the difference in the meanings is
subtle ("imply" and "infer").
Often misused Words that people often mistakenly use in place of
for... correct words. "Feel," for example, is often
misused for "think," "believe," or "estimate," as
in "I feel the report will be ready by the end of
the week."
14
Wintertree Software Inc. WStyle User's Guide
Passive verb Verbs that describe conditions or states of being,
rather than actions. Passive verbs are symptoms of
the passive voice. See the "Writing-Style
Statistics" section for more information.
Period or comma Punctuation placed incorrectly inside or outside
outside quotation quotation marks. Periods and commas should be
placed inside quotation marks. Colons and
semicolons should be placed outside.
Qualifying an Absolute adjectives which are qualified with
absolute comparison adjectives, as in "more complete,"
"most perfect," and "very unique."
Redundant Phrases like "connect together," "final end," and
"repeat again." It's amazing how easy it is to use
phrases like this without being aware that they
are redundant.
Sentence starts WStyle warns you if the first word of a sentence
with a small doesn't start with a capital letter. Sometimes
letter WStyle reports this in error; see the
"Limitations" section for more information.
Spelled-out WStyle reports spelled-out numbers that should be
numbers written in digit form. This includes any number
greater than nine.
Stilted "Fifty-cent" words that may make your document
hard to read.
Too few "(" or Parentheses that are closed but never opened. See
too many ")" "Too many '(' or too few ')'."
Too many "(" or Parentheses that are opened but never closed.
too few ")" WStyle also reports unbalanced braces ("{", "}")
and brackets ("[", "]"). WStyle reports these
problems at the end of your document.
Too many The sentence contains more prepositional phrases
prepositions than are permitted. Sentences with strings of
prepositional phrases are difficult to follow.
Example: "The leader of the committee on the
status of the study of incomplete projects could
not attend." You can change the number of
permitted prepositional phrases per sentence; see
the "Customizing WStyle" section.
15
WStyle User's Guide Wintertree Software Inc.
Unbalanced WStyle informs you if there is an odd number of
quotation marks quotation marks in your document. WStyle reports
this problem at the end of your document.
Usage error Incorrect combinations of words. Many of these
errors come from writing the way we hear; for
example, writing "suppose to" instead of "supposed
to," or "could of" instead of "could have."
Vague Adjectives that convey little meaning to the
reader, such as "nice" and "very." These should be
replaced with specific adjectives.
Wordy Phrases containing superfluous words. Eliminating
unneeded words tightens the text.
16
Wintertree Software Inc. WStyle User's Guide
Customizing WStyle
You can change some aspects of WStyle to suit your
preference:
* The severity level at which writing-style
problems are reported (see the "Setting
Options" and "Configuring WStyle" topics in
this section)
* The colors displayed on the screen (see the
"Configuring WStyle" topic)
* The writing-style problem patterns (see the
"Editing Problem Patterns" topic)
* Whether American or British spelling rules are
used (see the "Configuring WStyle" topic)
* The relative importance of the factors that
influence the overall-style statistic (see the
"Configuring WStyle" topic)
* The reading ability of your document's target
readers (see the "Setting Options" topic).
Setting Options
The "Options" action (F3) in WStyle's main screen
presents the options form:
Reporting Level: [5]
Target Reader Level: [10.0]
You can use this form to temporarily change the
way WStyle analyzes a document. Currently, you can
change the problem-reporting level and the target-
reader's level.
Note: You can also set the problem-reporting level
or the target-reader's level on WStyle's command
line. See the "Using WStyle" section for more
information.
Problem-reporting The problems reported by WStyle range from minor
level warnings and suggestions to serious errors. Each
problem reported by WStyle has a severity
associated with it. The reporting-level option
17
WStyle User's Guide Wintertree Software Inc.
defines the severity threshold for problems which
WStyle reports. If the problem-reporting level is
"0," WStyle reports all problems it detects. If
the level is "9," WStyle reports only the most
serious problems. Generally, selecting a high
reporting level decreases the number of problems
which WStyle reports, and selecting a low level
increases the number. For example, if you select
"5" as your problem-reporting level, WStyle
reports only problems with a severity of five and
above, but does not report problems with a
severity less than five. You can change the
severity of each problem pattern; see the "Editing
Problem Patterns" and "Configuring WStyle" topics
in this section.
Target-reader's The target-reader's level defines the average
level number of years of schooling you expect your
document's audience to have. The number of
schooling years is an approximation of reading
ability. WStyle uses this number in its writing-
style analysis (see the "Writing-Style Statistics"
section.
What number should you use here? Try to think of
the target-reader's schooling in terms of grades.
If you are writing for professionals, use 12.0 or
greater (college and beyond). If you are writing
for school-aged children, use their grade number.
For example, if you are writing a primary-school
story aimed at children in grade 2, enter 2.5. If
you are writing for a wide audience, use 10.0 (the
default).
Done (Esc) Once you have set the problem-reporting level or
target-reader's level, press the "Esc" key to
return to WStyle's main screen. WStyle uses the
entered values until you return to DOS. Next time
you run WStyle, it will revert to the default
values. To change the defaults, see the
"Configuring WStyle" topic.
18
Wintertree Software Inc. WStyle User's Guide
Configuring WStyle
You can configure some WStyle options by editing a
file called WSTYLE.INF. This file is located in
the WSTYLE directory you created when you
installed WStyle (see "Installing WStyle"). You
must change WSTYLE.INF from MS-DOS; you cannot
edit it from within WStyle.
Editing To change an option in WSTYLE.INF, you need a text
WSTYLE.INF editor capable of loading and saving ASCII files.
The "edlin" editor supplied with MS-DOS will do,
but unless you have used "edlin" before, we don't
recommend it. The "edit" editor supplied with MS-
DOS 5.0 is much easier to use. You can use any
text-editing program which can edit your
AUTOEXEC.BAT or CONFIG.SYS files.
Option entries The entries in WSTYLE.INF look like this:
REPORTING_LEVEL=3
The option name (in this case, "REPORTING_LEVEL")
appears to the left of the equal sign ("="). The
option value (in this case, "3") appears to the
right. This sample entry assigns the value "3" to
the REPORTING_LEVEL option. Note that no spaces
appear before or after the equal sign.
Comment lines WStyle ignores blank lines and lines beginning
with a "#" character in WSTYLE.INF. You can use
the "#" character to mark comment lines.
Error checking Edit the option values in WSTYLE.INF carefully:
WStyle does little checking.
The following paragraphs describe each
configurable option.
Problem-reporting The REPORTING_LEVEL option defines the default
level problem-reporting threshold. WStyle reports only
problems at this severity or greater. You can
temporarily change the reporting level when WStyle
runs with the "Options" action (see "Setting
Options"). You can also set the level on the
command line (see "Using WStyle"). The option
value is a number ranging from 0 to 9. Example:
REPORTING_LEVEL=5
19
WStyle User's Guide Wintertree Software Inc.
Spelling-rules The SPELLING_PREFERENCE option defines your
preference preference for American or British spelling rules.
For example, if you specify a preference for
American spelling rules, WStyle will report words
spelled in the British style. The option value can
be "American" or "British." Examples:
SPELLING_PREFERENCE=American
SPELLING_PREFERENCE=British
Problem-pattern The PATTERN_FILE option defines the location and
file name name of the file containing writing-style
patterns. WStyle uses these patterns when
analyzing a document. The file WSTYLE.WSP is
provided with WStyle, but you can create custom
pattern files (see "Editing Problem Patterns").
The option value is the path name of the problem-
pattern file. If you don't specify a full path,
WStyle looks for the file in the directory
containing WSTYLE.EXE. Examples:
PATTERN_FILE=D:\DOC\TOOLS\WSTYLE\FICTION.WSP
PATTERN_FILE=MEDICAL.WSP
Problem Most writing-style problem patterns are defined in
severities the WSTYLE.WSP file provided with WStyle. But some
patterns, because of their complexity, are built
in to the WStyle program itself. The
WORD_USAGE_SEVERITY, PUNCTUATION_SEVERITY, and
SPELLING_SEVERITY options define the severities of
the built-in problem patterns. The severity values
indicate the importance of the problems. You can
include the problems or exclude them by changing
the problem-reporting level.
Word-usage- The WORD_USAGE_SEVERITY option defines the
problem severity severity of problems related to word usage. These
problems include:
* Prepositions at the ends of sentences
* Too many prepositional phrases in a sentence
* Doubled words.
20
Wintertree Software Inc. WStyle User's Guide
Punctuation- The PUNCTUATION_SEVERITY option defines the
problem severity severity of problems related to punctuation. These
problems include:
* Incorrect forms of "e.g." and "i.e."
* Missing or incorrect spacing
* Punctuation placed incorrectly inside or
outside quotation marks
* Sentences starting with lower-case letters
* Unbalanced parentheses, brackets, and quotation
marks.
Spelling-problem The SPELLING_SEVERITY option defines the severity
severity of problems caused by conflicts between the
spelling rules you use and your stated spelling-
rule preference (see the SPELLING_PREFERENCE
option).
Note: Some spelling problem patterns are defined
in WSTYLE.WSP. The SPELLING_SEVERITY option does
not affect these.
Severity-option The option values for the severity options are
values numbers ranging from 0 to 9. Examples:
WORD_USAGE_SEVERITY=7
PUNCTUATION_SEVERITY=4
SPELLING_SEVERITY=4
Word The STRICT_WORDS option indicates whether WStyle
acceptability should exclude character strings which do not
appear to be valid English words. The option value
is "True" or "False." If you use WStyle to analyze
documents prepared by a word-processing program,
set the STRICT_WORDS option to "True." WStyle will
ignore most formatting information inserted by
your word-processing program. If you use WStyle to
analyze ASCII text files, set the STRICT_WORDS
option to "False." WStyle will then treat all
alphabetic strings in your document as words. See
the "Limitations" section for more information.
Examples:
STRICT_WORDS=True
STRICT_WORDS=False
21
WStyle User's Guide Wintertree Software Inc.
Style-factor WStyle calculates the "Overall style score"
weights statistic from several factors:
* Use of the active voice over the passive voice
* Word economy
* Readability
* Word choice.
WStyle analyzes your documents against these
factors. It bases the overall-style score
statistic (see the "Writing-Style Statistics"
section) on the weighted sum of the factors. The
ACTIVE_VOICE_WEIGHT, WORD_ECONOMY_WEIGHT,
READABILITY_WEIGHT, and DICTION_WEIGHT options
define the relative values of each factor to the
overall-style score. The option values are numbers
ranging from 0 to 100. Each weight indicates the
relative importance of its associated factor
expressed as a percentage. The values assigned to
all four weight options must total 100.
Default weights The default weights included with WStyle were
calibrated by examining a ranked collection of
writing samples. The samples were ranked according
to our definition of writing-style quality (see
"Writing Style"). You may wish to change the
weights because you don't agree with the
importance we place on each factor. You may, for
example, write for an organization that favors the
use of the passive voice. Our bias in favor of the
active voice will unfairly score your writing
style.
Changing the If you decide to define a new set of weights, you
weights may want to use the method we used. Obtain a
collection of writing samples with quality ranging
from poor to excellent (judged by whatever
standards you prefer). Sort the samples in order
of quality. Have WStyle analyze each sample. Using
trial-and-error, change the style weights until
WStyle scores the samples in the same order in
which you sorted them. You may need to adjust the
target-reader's level to suit the samples. Your
degree of success in this process may vary
depending on how closely your notion of writing-
style quality agrees with ours.
22
Wintertree Software Inc. WStyle User's Guide
Some example weight options follow (note that the
values total 100):
ACTIVE_VOICE_WEIGHT=25
WORD_ECONOMY_WEIGHT=30
READABILITY_WEIGHT=20
WORD_CHOICE_WEIGHT=25
Target-reader's The TARGET_READER_LEVEL option defines the default
level average years of schooling you expect the readers
of your document to have. You can temporarily
change the target-reader's level when WStyle runs
with the "Options" action (see "Setting Options").
You can also set the level on the command line
(see "Using WStyle"). The option value is a
positive floating-point number. Example:
TARGET_READER_LEVEL=9.8
Screen colors If you use WStyle with a color monitor, you can
change the colors WStyle uses. You can
independently set the foreground (text) and
background colors of the following screen areas:
* Context: Used to show which word is being
checked. Also used to present the document
statistics, problem pattern, and options.
* Problem report: Used to present writing-style
problems.
* Progress bar: Used to draw a horizontal bar
showing how much of the document has been
checked.
* Function keys: Used to present action names and
their associated function keys.
* Alert: Used to display errors and other
important messages.
Color values Each color option value is a number ranging from 0
to 15. Use the following table to determine the
number for each color:
23
WStyle User's Guide Wintertree Software Inc.
0 Black 8 Dark gray
1 Blue 9 Light blue
2 Green 10 Light green
3 Cyan 11 Light cyan
4 Red 12 Light red
5 Magenta 13 Light magenta
6 Brown 14 Yellow
7 Light gray 15 White
Here are some example color options:
CONTEXT_FG_COLOR=7
CONTEXT_BG_COLOR=1
PROBLEM_FG_COLOR=1
PROBLEM_BG_COLOR=3
PROGRESS_FG_COLOR=4
PROGRESS_BG_COLOR=7
FKEY_FG_COLOR=1
FKEY_BG_COLOR=15
ALERT_FG_COLOR=14
ALERT_BG_COLOR=4
Prepositional- The PREPOSITION_LIMIT option defines the maximum
phrase limit number of prepositional phrases considered
acceptable in a sentence. WStyle reports sentences
containing more prepositional phrases than the
limit permits. Typical prepositional phrases
include "the roof of the house" and "the man in
the moon." While these are acceptable
individually, they can make sentences hard to
follow and awkward when they are repeated. The
option value is a positive number. Example:
PREPOSITION_LIMIT=4
Active-voice The ACTIVE_VOICE_LIMIT option defines the minimum
percentage limit percentage of sentences which use the active
voice. WStyle compares your document's active-
voice statistics against this limit (see the
"Writing-Style Statistics" section). The option
value is a number ranging from 0 to 100. Example:
ACTIVE_VOICE_LIMIT=60
24
Wintertree Software Inc. WStyle User's Guide
Editing Problem Patterns
You can add, change, or delete the problem
patterns WStyle uses to check your documents. Edit
WStyle's problem patterns by selecting the
"Patterns" action (F3) from WStyle's main screen.
WStyle comes with a large set of problem patterns.
You don't need to edit the problem patterns to use
WStyle. However, you may want to define your own
problem patterns. You may also want to change the
suggestion WStyle offers when it reports a
problem, or change the severity of a problem.
Custom pattern You can also define your own set of custom problem
files patterns for different purposes. Possibilities
include pattern sets for fiction, medical or legal
terminology, children's books, advertising copy,
and song lyrics.
To create a custom problem-pattern file, copy
WSTYLE.WSP to some appropriate name (e.g.,
FICTION.WSP). Change the PATTERN_FILE option in
WSTYLE.INF to the name of the new file (see the
"Configuring WStyle" topic). Run WStyle and edit
the patterns as needed for your purpose.
Removing problem You can delete WStyle's problem patterns, but we
patterns do not recommended this. Instead, change the
reporting level of the unwanted problem pattern to
"0" and set your reporting level option (see "Set
Options") to at least "1."
Note: If you add many problem patterns, you may
run out of memory. In this case, you must delete
some of the existing patterns to make room for the
new ones.
WStyle shows one problem pattern at a time on the
screen:
Pattern: [a criteria ]
Description: [Usage error ]
Suggestion: [Criteria: plural ]
Severity: [8]
25
WStyle User's Guide Wintertree Software Inc.
Moving around The "Page Up" and "Page Down" keys display the
previous and next patterns. WStyle presents the
patterns in alphabetical order.
A problem pattern consists of four fields:
"Pattern," "Description," "Suggestion," and
"Severity." Use the "Up Arrow" and "Down Arrow"
keys to move the cursor between fields.
Editing a problem You can change the contents of a field using
pattern standard editing keys. Typed characters are placed
in the field at the cursor position. Note that
each field has a maximum size; WStyle beeps if you
try to type past the end of a field. The "Left
Arrow" and "Right Arrow" keys move the cursor back
and forth in the current field. The "Delete" key
deletes the character under the cursor. The
"Backspace" key deletes the character to the right
of the cursor. The "Clear" action (F6) clears the
current field.
Problem pattern The "Pattern" area contains a single writing-style
pattern. The words that form a pattern may contain
the wildcard characters "*" and "?". These are the
same wildcard characters used on the DOS command
line. In case you are not familiar with them, "*"
matches any group of zero or more characters. "?"
matches any single character. WStyle limits the
wildcard characters to words. WStyle considers a
word to be any collection of alphabetic
characters. A word may contain embedded
apostrophes. WStyle ignores other punctuation
appearing in patterns. "Walk*" matches the words
"walk", "Walks", "walking", and "Walkley's".
WStyle is not case-sensitive. "*ing" matches any
word ending in "ing". "A?*" matches any word that
is at least two letters long and starts with "A"
or "a". "*" matches any word. You can use
wildcards in any word within a pattern. The first
word in a pattern must start with a letter, not a
wildcard. A pattern may contain up to eight words.
Description Use the "Description" field to define a brief
message that explains the problem. For cons-
istency, try to use one of the descriptions WStyle
uses (see the "Writing-Style Problems" section).
Suggestion Use the "Suggestion" field to recommend a way of
fixing the problem.
26
Wintertree Software Inc. WStyle User's Guide
Severity Enter a number between 0 and 9 in the "Severity"
field to define the severity of the writing-style
problem.
Problem-pattern The actions at the bottom of the screen tell
editor actions WStyle what to do with the displayed pattern.
F1-Change F2-Add F3-Delete F4-Search
F5-Save F6-Clear Esc-Done
Change (F1) To change the displayed problem pattern, edit the
pattern, description, suggestion, or severity.
Next, invoke the "Change" action (F1).
Add (F2) To add a new writing-style problem pattern, edit
the displayed pattern, description, suggestion,
and severity to form a new pattern. Next, invoke
the "Add" action (F2).
Delete (F3) The "Delete" action removes the displayed problem
pattern. As noted above, deleting the problem
patterns provided with WStyle is not recommended.
Search (F4) Use the "Search" action to locate a problem
pattern containing a search key. WStyle prompts
you for the key to locate:
Enter search key:
Enter or edit the key text, then press "Enter."
WStyle searches for the key text in the "Pattern,"
"Description," and "Suggestion" fields. The
"Search" action always searches from the first
problem pattern. Use the "Search next" action to
search for the next occurrence of the search key.
Search next Use the "Search next" action to locate the next
(Shift/F4) occurrence of the last search key entered using
the "Search" action. The "Search next" action
looks for the key starting with the problem
pattern following the displayed one.
Save (F5) The "Save" action saves the updated problem
patterns to disk. WStyle will use the updated
patterns each time you run it.
Clear (F6) The "Clear" action deletes all the characters from
the field on which the cursor is located. Use the
"Clear" action to quickly empty a field.
27
WStyle User's Guide Wintertree Software Inc.
Done (Esc) The "Done" action returns you to WStyle's main
screen. When you invoke the "Done" action, the
changes you have made take effect, but are not
saved permanently. When you exit WStyle, the
changes you made to the problem patterns will be
lost. To save your changes permanently, use the
"Save" action.
Note: If you change many problem patterns, you may
run out of string space. When this happens, save
your changes (F5), then exit WStyle. Rerun WStyle
and return to the problem-pattern editor. If
WStyle still reports "Out of string space," you
will have to delete some of the existing problem
patterns before you can add new ones.
28
Wintertree Software Inc. WStyle User's Guide
Limitations
WStyle works mechanically. It matches a set of
patterns against the words and phrases in a
document. When it finds a match, it responds by
displaying a problem report or recording a
statistic. Like grammar checkers and other similar
programs, WStyle has no idea of the meaning behind
the words in a document. Sometimes it makes
mistakes. For example, it warns that the phrase
"number of" is often mistakenly used in place of
"amount of," even in a sentence like "Always keep
the telephone number of your fire department
handy." You must consider each problem reported by
WStyle to decide whether it is valid and
significant. WStyle is not a substitute for an
independent review.
WStyle does not detect every writing-style
problem. WStyle's assessment of writing style does
not imply the writing is fit for any purpose.
Tense Although it can recognize verbs in any tense,
WStyle always makes its suggestions in the present
tense. WStyle suggests you use "connect" instead
of "connected together" or "connecting together."
You may have to mentally translate WStyle's
suggestions to the correct tense.
Hyphenation codes Some word processors insert control codes within
words to separate syllables for hyphenation. These
control codes may confuse WStyle, causing it to
miscount words or miss a problem it would
otherwise catch. Disable your word processor's
hyphenation feature if this is the case (see your
word processor's user guide).
Embedded Some word processors embed strings of characters
character strings (for example, font names) within document files
for control purposes. These strings are not
normally visible. To WStyle, however, they are
indistinguishable from words. You may see them in
the context area, and they may make the word count
and other statistics inaccurate. The easiest way
29
WStyle User's Guide Wintertree Software Inc.
to avoid this problem is to use WStyle to check
your document before adding special effects such
as font changes and figures. If you can't do this,
save your document in ASCII format before checking
it with WStyle. Setting the STRICT_WORDS option to
"True" may also help (see the "Customizing WStyle"
section).
Non-alphabetic WStyle normally ignores collections of characters
strings that do not appear to be valid words. This
includes numbers, times, and special characters.
If you would like to disable this feature, set the
STRICT_WORDS option to "False" (see the
"Customizing WStyle" section).
Sentences WStyle recognizes sentence endings by terminating
punctuation: periods, question marks, and
exclamation marks. WStyle may incorrectly believe
a sentence has ended when this punctuation appears
within a sentence. WStyle does, however, recognize
common abbreviations terminated with periods
within sentences.
30
Wintertree Software Inc. WStyle User's Guide
References
The following books were consulted during the
preparation of WStyle.
Baugh, L. Sue, Essentials of English Grammar,
Passport Books, Lincolnwood, Ill.
Lewis, Norman, Better English, Dell, NY.
Montgomery, Michael and Stratton, John, The
Writer's Hotline Handbook, New American Library,
NY.
Northey, Margaret, Making Sense: A Student's Guide
to Writing and Style, Oxford University Press,
Toronto.
Opdycke, John B., Harper's English Grammar, Harper
and Row, NY.
Rosen, Leonard, The Everyday English Handbook,
Dell, NY.
Strunk, William and White, E.B., The Elements of
Style, Macmillan Publishing, NY.
Waldhorn, Arthur, and Zeiger, Arthur, English Made
Simple, Doubleday, NY.
Webster's Dictionary of the English Language,
Lexicon Publications, NY.
31
